Meeting Pearls 1

home *** CD-ROM | disk | FTP | other *** search

/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / installed_progs / comm / ums / developer.lha / Developer / doc / ums.doc

Wrap

Text File | 1993-09-23 | 46.0 KB | 1,224 lines

TABLE OF CONTENTS ums.library/--background-- ums.library/CannotExport ums.library/DeleteUMSMsg ums.library/ExportedMsg ums.library/FreeUMSConfig ums.library/FreeUMSMsg ums.library/LogUMS ums.library/ReadUMSConfig ums.library/ReadUMSMsg ums.library/UMSErrNum ums.library/UMSErrTxt ums.library/UMSLogin ums.library/UMSLogout ums.library/UMSRLogin ums.library/UMSSearch ums.library/UMSSelect ums.library/WriteUMSConfig ums.library/WriteUMSMsg ums.library/--background-- ums.library/--background-- $VER: 10.21 (28-Aug-93) COPYRIGHT This document is (C) 1992 by Martin Horneffer. It may freely be copied and distributed, as long as the text is unchanged and this copyright notice is left intact. GENERAL UMS stands for "Universal Message System". This means that UMS allows to treat and read all kinds of messages ('e-mail' and 'news') as universally and efficiently as possible. The user should not need to care about what network a message comes from or goes to/through and what format is used, he or she should be able to concentrate totally on the messages' contents. In order to achieve this goal, UMS does two things: 1) define an universal format for messages where messages in all formats and from all networks can be stored in without loss of information and nevertheless being randomly interchangeable. 2) implement a central, network-independent database-mamagement that allows to store and read/retrieve messages in the UMS format as efficiently as possible. For the message format, please read the separate documentation. The implementation of the Message Base Processor ('MBP') is based on the server/client- concept. Clients address the server to get or put messages. The server manages the storage and retrieval of messages and controls the different client's access-rights to the system. The common interface between client and server is a set of functions described in this document. Clients are - simple USERS that read and write messages (using programs called 'newsreaders'), - a special kind of user, the 'SYSOP', which has additional rights and tools to administer the system, - IMPORTERS, that get messages form other systems and put them into the local system after converting them to the UMS format, and - EXPORTERS, that look for all NEW messages in the system and send them to other systems after converting them into the specific format. The MBP controls which user may read what message and, in the same way, which exporter needs to export or forward what message. It cares about whether a message can or cannot be correctly sent to its destination. The MBP also performs dupe-checking and reply-chaining on Message-IDs. TAGS UMS uses some bit-masking in tag values to indicate some special types of tag data: if bit 13 is set (tag & 0x2000), the tag data is a STRPTR, i.e. a pointer to a null-terminated string. if bit 14 is set (tag & 0x4000), the tag is considered a 'var- parameter' (e.g. LONG *). I.e. the tag.data entry must contain a pointer to the real data, which will be set/changed by the called function. if both bits 13 and 14 are set ((tag & 0x6000)==0x6000), the tag is a pointer to a string pointer which will be set/changed (STRPTR *). if none of these bits is set, the data in most cases is a simple integer parameter (e.g. LONG or LONGBITS). ums.library/CannotExport ums.library/CannotExport NAME CannotExport -- Mark a message as not being exportable. SYNOPSIS CannotExport( login, msgNum, error ) D2 D3 D4 VOID CannotExport( LONG, LONG, STRPTR ); FUNCTION Tell the MBP that you cannot export this message, due to any reason. The MBP will then look if other exporters still could be able to export the message or do some error processing otherwise. It may use the supplied error-string therein. This error-string should be a short description why the message could not be exported. By convention it should not be longer than 80 bytes. INPUTS msgNum - Number of the message. error - Short string (<80 chars). NOTES This function may only be called by exporters. See also ExportedMsg(). BUGS The MBP currently does not write a bounce mail to the author of the mail, but sets a special global bit instead, which would allow a 'bounce daemon' to automatically write bounce mails. SEE ALSO ExportedMsg() ums.library/DeleteUMSMsg ums.library/DeleteUMSMsg NAME DeleteUMSMsg -- Delete a message. SYNOPSIS success = DeleteUMSMsg( login, msgNum ) D0 D2 D3 BOOL DeleteUMSMsg( LONG, LONG); FUNCTION This functions deletes a message, specified by number, from the UMS MB. It does not necessarily free space on the hd, but it removes the message logically from the MB so that no other user can access it anymore and it won't affect the dupe-check for new messages. The MBP may need reorganization to physically remove logically deleted messages. INPUTS msgNum - Number of the message to be deleted. As returned by UMSSearch() or WriteUMSMsg(). RESULT success - Inidcates whether the message was actually deleted or not. It will be not deleted if you don't have write-access to this message or the message doesn't exist. NOTES The number of a message is valid only as long as you are logged in. After UMSLogout() messages numbers may change! So you always have to use the real Message-ID to remember a message persistently. ums.library/ExportedMsg ums.library/ExportedMsg NAME ExportedMsg -- Mark a message as being successfully exported. SYNOPSIS ExportedMsg( login, msgNum ) D2 D3 VOID ExportedMsg( LONG, LONG ); FUNCTION Tells the MBP that a message has been successfully exported. The MBP uses this information to prevent other exporters from wrongly exporting this message a second time or writing a bounce message. Every exporter that exports a message from the local UMS system to any other system or network MUST call either ExportedMsg() or CannotExport() for each message it has processed. This is valid for private messages as well as for public messages (news). The MBP will decide what has to be done in any of these cases. INPUTS msgNum - Number of the exported message. NOTES This function may only be called by exporters. SEE ALSO CannotExport() ums.library/FreeUMSConfig ums.library/FreeUMSConfig NAME FreeUMSConfig -- Free a string returned by ReadUMSConfig(). SYNOPSIS FreeUMSConfig( login, string) D2 D3 FreeUMSConfig( LONG, STRPTR); FUNCTION Frees the buffer for a string allocated and returned by ReadUMSConfig(). After 'FreeUMSConfig(string)', 'string' will be invalid. INPUTS string - string returned by ReadUMSConfig(). SEE ALSO ReadUMSConfig() ums.library/FreeUMSMsg ums.library/FreeUMSMsg NAME FreeUMSMsg -- Free buffers associated with a certain message. SYNOPSIS FreeUMSMsg( login, msgNum ) D2 D3 FreeUMSMsg( LONG, LONG ); FUNCTION Frees all the buffers associated with a certain message. ReadUMSMsg() allocates the buffers, this function frees them. INPUTS msgNum - number of the message previously read with ReadUMSMsg(). NOTES With FreeUMSMsg() all STRPTRs obtained with ReadUMSMsg() that are concerned with this certain message become invalid. You can have multiple ReadUMSMsg() on the same message but only one FreeUMSMsg(). SEE ALSO ReadUMSMsg() ums.library/LogUMS ums.library/LogUMS NAME LogUMS -- Write an entry to the global UMS logfile. SYNOPSIS LogUMS( login, level, format, args ) D2 D4 D5 D6 LogUMS( LONG, LONG, STRPTR, LONG * ); LogUms( login, level, format, ... ) LogUms( LONG, LONG, STRPTR, ... ) FUNCTION Write a short message to the UMS logfile, doing printf-style formatting on supplied parameters. Rather than creating all its own logfile, an application should use this function to report its actions and/or errors. This makes it easier for the user to get an overview on what is happening in his system - he only has to look in ONE logfile. LogUMS() uses a 'level'-parameter to decide whether a message should actually be written to the logfile or be ignored. The lower this number, the more important is the message. Choose it as follows: 1-4: an ERROR. 1=very fatal error, 4=recoverable error. 5-7: general information or report. 8-9: information that is not useful for normal operation, but used for debugging purposes. Of course messages with higher level-values should appear more frequently than those with low level-values. INPUTS level - Number between 1 and 9. format - Printf-style format-string. See RawDoFmt() for more information on formatting. args - Arguments for the format-string. SEE ALSO RawDoFmt() ums.library/ReadUMSConfig ums.library/ReadUMSConfig NAME ReadUMSConfig -- Read something from the global configuration. SYNOPSIS string = ReadUMSConfig( login, tags ) D0 D2 D3 STRPTR ReadUMSConfig( LONG, struct TagIten * ); string = ReadUMSConfigTags( login, tag1, ... ) STRPTR ReadUMSConfigTags( LONG, ULONG, ... ); FUNCTION Read a config object from the global UMS configuration. Whenever possible, applications should use the global UMS configuration and this function instead of extra config-files. A 'config-string' is a null-terminated string identified by an unique name. Similar to shell- and environment-variables config-strings can be global (same for all users) or local (only visible to a certain user). Other config-objects are 'users' (with aliases and local strings), 'akas' and 'netgroups'. In order not to mix up config-strings of different applications, their names should have the id of the application and a dot prepended. E.g. "fido.outbound", "fido.inbound", "uucp.uuspool", "magicmail.publicScreenName", etc. The MBP enforces this convention by not accepting config elements without a dot ("."). Names for config elements are case-insensitive. This function buffers the returned string until it is freed with FreeUMSConfig() or (UMSLogout()). INPUTS The following tags are allowed: CfgGlobalOnly : (none) read just global config-elements, ignore local ones. CfgUser : STRPTR read config elements local to another user. You must specify the name of the other user here. This contradicts CfgGlobalOnly! CfgMatchPattern : STRPTR (Not yet implemented in V9.) Only search for config elements that match a given pattern. The following tags are mutually exclusive. Use exactly one of them. CfgName : STRPTR read a config-string with given name. CfgUserName : STRPTR get the 'realname' for a user with a given alias. CfgNextVar : STRPTR get the name of the next config variable. This allows you to scan all existing variables. On first invocation you set the tag's data to NULL and get the name of the first var. Then you always set it to what has been returned on the last call. When NULL is returned, you're finished. Can (but needn't) be combined with tag CfgGlobalOnly or tag CfgUser. CfgSameNetgroup : STRPTR (Not yet implemented in V9) get the next groupname for the same netgroup. Any number of groupnames may be configured as identical 'netgroups'. Using this tag you can get another name for the same 'netgroup' as the given groupname. Using this tag repeatedly you can cycle trough all names for the same group. Because these are organized in a circular structure you must do a string-compare with the original string to detect when you are finished. This returns NULL only when the given string doesn't indicate a netgroup. CfgNextNetgroup : STRPTR CfgNextUser : STRPTR CfgNextAlias : STRPTR (Not yet implemented in V9) These tags allow you to scan all existing configuration objects. On first invocation you set the tag's data to NULL and get the name of the first element. Then you always set it to what has been returned on the last call. When NULL is returned, you're finished. You may use CfgUser together with CfgNextAlias and CfgNextString. CfgGlobalOnly is redundant as it's the default. RESULT string - a pointer to the desired config element, or NULL. BUGS Some of the tags are not implemented yet (as indicated). Tell the author (Martin Horneffer) when you need them! SEE ALSO FreeUMSConfig(), WriteUMSConfig() ums.library/ReadUMSMsg ums.library/ReadUMSMsg NAME ReadUMSMsg -- Read (parts of) a message. SYNOPSIS success = ReadUMSMsg( login, tags ) D0 D2 D3 BOOL ReadUMSMsg( LONG, struct TagItem * ); success = ReadUMSMsgTags( login, tag1, ... ) BOOL ReadUMSMsgTags( LONG, ULONG, ... ); FUNCTION Read a message or any parts of it. INPUTS The following tags are allowed: RMsgNum : LONG specify which msg to read. This tag MUST be used! RHeaderLength : LONG * you have to pass a pointer to a LONG here. This LONG will be set to the length of the message-header in bytes. I.e. the length of all text-fields considered to belong to the 'header' of a message. RTextLength : LONG * like RHeaderLength, but the length of the message-text. These are all other fields. RMsgDate : LONG * the date the message has been written to the message-base (also referred to as the 'receive-date'). In AmigaDOS Format (seconds since 1.1.1978). RChainUp, RChainDn, RChainLt, RChainRt : LONG * reply-chaining. Since a message can only refer to one other (older) message, but have multiple other (newer) messages referring to it, a tree is built out of this 'comment-chaining'. ChainUp points to the referred message. ChainDn points to one of the messages that comment on the current one. ChainLt and ChainRt point to other messages which share the same ChainUp. The LONG you supply a pointer to in the tag's data will either be set to zero (when there is no such chain) or to the number of a message. RGlobalFlags : LONGBITS * global flags for this message. In the MB every message has exactly one set of global flags. See <ums.h> for the meaning of these flags. RUserFlags : LONGBITS * user-flags for this message. Every user of the MB has one set of user-flags for each message. See <ums.h> for the fixed or suggested meanings of these flags. RLoginFlags : LONGBITS * login-flags for this message. Every login has a private set of flags for each message. In contrast to global or user-flags, login-flags are NOT saved and vanish on UMSLogout(). They are set to zero on UMSLogin(). RHardLink, RSoftLink : LONG * a pointer to another link in the circular linked list of linked messages. Zero if a real message (no link). Since message-links can be either hard or soft, but not both at the same time, only one of these can be non-zero. RDateStyle : LONG use this tag and set its data to 1 if you want to get an old-style 'receive-date'. Don't use this tag or set its data to zero otherwise. RMsgText, .. RMsgText + 127 : STRPTR * tell UMS that you want to read the specified text-field and supply a place for a pointer to it. This will be set to NULL if the field doesn't exist or you're not allowed to read it. RTextFields : UMSMsgTextFields if you supply a pointer to an array of 128 STRPTR here, it will be set to the read text-fields. Useful for reading a whole message without having to specify a tag for each possible text-field. RReadHeader : (none) tell UMS that you want to read all header-field. Useful in combination with RTextFields only. RReadAll : (none) tell UMS that you want to read the message-text, too. Useful in combination with RTextFields only. The following tag was not implemented in ums.library until V9.70 ! RIDStyle : LONG choose the style of local message IDs. There are two possible formats of 'local' message IDs (= the IDs created by the local system): a) a simple decimal number that is unique on the local system b) this decimal number followed by "@" and the domain- address of the local system. This conforms with RFC822/1036. Old (obsolete) Version of ums.library (< V9.70) still use format a), but since V9.70 versions use format b) in order to make things cleaner and make life easier for exporters. With format a) exporters must append the domain-address to IDs themselves, with format b) they needn't care about whether an ID is local or not. As an interim solution this tag allows to specify the desired format. Its data set to 1 forces format a), 0 (default) forces format b). RNoUpdate : LONG when reading its message-text, a message is usually updated by having its 'Old'-flag set in your user-status. If you don't want the Old-flag to be set, use this tag and set its data to 1. RESULT success - whether your attempt to read the message was successful or not. NOTES The message will be buffered, so you can easily use all the returned STRPTRs. You have to use FreeUMSMsg() to free the buffers allocated for a certain message. An user or exporter usually wants to read a single message only once. To make this easy, ReadUMSMsg() checks whether the user reads the 'MsgText' of a message, and, if so, sets the 'Old'-Flag in the users status if it wasn't already set. So the user (or exporte) only needs to ask for this flag to be unset when using 'UMSSearch()' before 'ReadUMSMsg()' and will automatically avoid reading the same message a second time. SEE ALSO FreeUMSMsg(), UMSSearch() ums.library/UMSErrNum ums.library/UMSErrNum NAME UMSErrNum -- Return the number of the last error. SYNOPSIS error = UMSErrNum( login ) D0 D2 WORD UMSErrNum( LONG ); FUNCTION UMS functions usually return zero to indicate an error. When this happens, this routine may be called to get a more specific error code. By some means, this routine corresponds to an UMS login as dos.library/IoErr() does to a DOS-process. INPUTS login - Login handle as returned by UMSLogin() or UMSRLogin(). RESULT error - an error number Possible UMS error numbers can be grouped into 4 ranges: 0: no error at all, the last UMS function call was successful. 100-199: a slight error. The last functions call was not successful, but may succeed if some slight changes will be made to its parameters. E.g. when an importer tries to import a message it migth get error '103' when the to-user does not exist on the local system. It then should change some message-fields in order to forward the message to the sysop. 200-299: a real error. The last function call was not successful at all and should not be retried. 300-: a severe error concerning the whole system. E.g. the server has terminated. A program receiving such an error is recommend to UMSLogout() and terminate asap. SEE ALSO UMSErrTxt() ums.library/UMSErrTxt ums.library/UMSErrTxt NAME UMSErrTxt -- Return a string describing the last error. SYNOPSIS text = UMSErrTxt( login ) D0 D2 STRPTR UMSErrTxt( LONG ); FUNCTION When an UMS functions fails and/or UMSErrNum() returns a nonzero value, you should use this routine to get a brief English description of the last error. Interactive programs should display this text to the user. Non-interactive programs should use this text in their logfile. INPUTS login - Login handle as returned by UMSLogin() or UMSRLogin(). RESULT text - Pointer to a String. NOTES This is similiar to dos.library/Fault(), but it doesn't copy any string, it just returns a pointer. You may NEVER change the string returned by UMSErrTxt()! ums.library/UMSLogin ums.library/UMSLogin NAME UMSLogin -- Open the UMS MB for a certain user. SYNOPSIS login = UMSLogin( user, passwd ) D0 D2 D3 LONG UMSLogin( STRPTR, STRPTR ); FUNCTION Opens the MB, checking the password and returning a 'login' handle when successful. The given 'user'-name must be known to the MBP and the password 'passwd' must match. If the MBP does not already run, it will be automatically started. All other functions in ums.library requiry a valid 'login' handle to work. INPUTS user - Name or 'alias' of an user known to the MBP. passwd - The user's correct password. A pointer to the null-string is allowed, NULL itself isn't. RESULT login - Internally used handle to track and remember resources associated with each Login. Different for a single user's multiple Logins. One Login may be used only by one process at a time. Greater 0 on success, lower or equal 0 on failure. EXAMPLE long login = UMSLogin( "Martin Horneffer", "secret"); NOTES If multiple MBPs are running on the same machine, you may use UMSRLogin() to specify which one to use. SEE ALSO UMSRLogin(), UMSLogout() ums.library/UMSLogout ums.library/UMSLogout NAME UMSLogout -- Close a Login and free its resources. SYNOPSIS UMSLogout( login ) D2 VOID UMSLogout( LONG ); FUNCTION Close a Login obtained with UMSLogin() or UMSRLogin() and free all related resources. INPUTS login - Login handle as returned by UMSLogin() or UMSRLogin(). BUGS Used to need much stack under some circumstances, thus crashing some programs. This should be fixed now (V9.66). SEE ALSO UMSLogin(), UMSRLogin() ums.library/UMSRLogin ums.library/UMSRLogin NAME UMSRLogin -- Open a certain UMS MB for a certain user. SYNOPSIS login = UMSRLogin( server, user, passwd ) D0 D2 D3 D4 LONG UMSRLogin( STRPTR, STRPTR, STRPTR ); FUNCTION Like UMSLogin(), but specifies a special MB. This permits having multiple MBPs running on the same machine. It will also be used for specifying a MBP on a local network. INPUTS server - Name of the MB. user - Name or 'alias' of an user know to the MBP. passwd - The user's correct password. A pointer to the null-string is allowed, NULL itself isn't. RESULT login - Internally used handle to track and remember resources associated with each Login. Different for a single user's multiple Logins. One Login may be used only by one process at a time. Greater 0 on success, lower or equal 0 on failure. EXAMPLE long login = UMSRLogin( "test-server", "Martin Horneffer", "secret"); NOTES UMSRLogin( "", x, y) and UMSRLogin( NULL, x, y) both are equal to UMSLogin( x, y). SEE ALSO UMSLogin(), UMSLogout() ums.library/UMSSearch ums.library/UMSSearch NAME UMSSearch -- Search a message from the MB. SYNOPSIS msgNum = UMSSearch( login, tags ) D0 D2 D3 LONG UMSSearch( LONG, struct TagItem * ); msgNum = UMSSearchTags( login, tag1, ... ) LONG UMSSearchTags( LONG, ULONG, ... ); FUNCTION Search the first (or next) message in the MB that fullfills certain criteria. When you want to read certain messages from the MB, it is recommended that you first select these messages with UMSSelect() and then alternately use UMSSearch() and ReadUMS() to get all these messages. INPUTS Allowed tags: SearchLast : LONG specify the last message NOT to search. This tag allows you to cycle trough all messages fullfilling the same criteria: set this to zero and invoke UMSSearch() the first time. Check the result and if it's not zero, put it in this tag and invoke UMSSearch() again. Repeat this until it returns zero. SearchDirection : LONG set the search direction. 1 means search forward (to higher numbers), -1 means search backwards (to lower numbers) and 0 lets the MBP decide what sequence to use. This needn't be exactly forwards or backwards. It might be in a completely different order. When you don't depend on a certain search-direction, use 0 or omit this tag. SearchGlobal : (none) SearchLocal : (none) SearchUser : STRPTR SearchMask : LONGBITS SearchMatch : LONGBITS search for a matching status; like SelReadGlobal, SelReadLocal, SelReadUser, SelMask and SelMatch with UMSSelect(). WMsgText, .. WMsgText + 127 : STRPTR search for a matching text; as for UMSSelect(). Only one field can be searched for at a time. SearchQuick : (none) Enable 'quick-search'. This must be combined with exactly one of WMsgText+1 .. WMsgText+31. quick-searches are possible for exact string searches only, they must not be combined with patterns and they are only possible for fields that have an index. They don't guarantee that the returned message's field actually matches the given string, altough mistakes are very unlikely. But they are fast! (see NOTES below) SearchPattern : LONG indicate whether the string to be searched for is an exact string (0), an AmigaDOS pattern (1) or UMS should try to find out (2). RESULT msgNum - numer of a/the searched message; zero if not found. NOTES Although LONGBITS are used in the definition, the current implementation only uses/supports the lower 16 bits. Performance: when searching for strings, different calls to UMSSearch() may significantly vary in performance. There are three general possibilities: 1) quick-searches: very fast, no access to the hard-disk needed (once the right index is loaded into memory). Only possible if tag 'SearchQuick' specified. 2) indexed searches: fast, in most cases only one, short access to hd is needed; a few more in really bad situations. If the 'header'-file is sufficiently buffered, no accesses to the hd may occur. Possible if searching for exact strings in indexed fields. 3) other searches (non-indexed or patterns): slow, many data will have to be read from hd. If the field searched for is in the 'header'-file and it's heavily buffered, no accesses to the hd may occur. Nevertheless the search will consume much CPU-time. Search for status!!! Searching for a matching status only (i.e. not searching for a string) is always very fast. When doing non-indexed- or pattern-search, combine with status to reduce the amount of data to be searched through! SEE ALSO UMSSelect(), ReadUMS(), <ums.h> ums.library/UMSSelect ums.library/UMSSelect NAME UMSSelect -- Select messages. SYNOPSIS count = UMSSelect( login, tags ) D0 D2 D3 LONG UMSSelect( LONG, struct TagItem * ); count = UMSSelectTags( login, tag1, ... ) LONG UMSSelectTags( LONG, ULONG, ... ); FUNCTION Select messages in the MB according to various criteria. To 'select' here means to set or unset some flags, which then can be used by UMSSearch(), stored or transferred to another user. UMSSelect() can only do one operation upon every invocation. An operation usually looks for all messages that fullfill the specified criteria and then selects them in a specified way. When you want to select messages by different, logically combined criteria, you may need to call UMSSelect() more than once and use some temporary flags. However, very few calls to this functions usually should suffice. INPUTS The following tags control the selection of messages. Thus, they somehow specify the 'output' of the select operation. SelWriteGlobal : (none) manipulate global flags on the selected messages. SelWriteLocal : (none) manipulate your local login-flags. SelWriteUser : STRPTR manipulate another user's user-flags. You must specify the users name (or alias). SelWriteGlobal, SelWriteLocal and SelWriteUser are mutual exclusive -- you can manipulate only one flag-table at a time. When specifying none of these tags, your user-flags will be manipulated as default. SelSet, SelUnset : LONGBITS on each selected message the 'SelUnset' flags are cleared and then the 'SelSet' flags are set. ['status = (status & ~unset) | set;'] When writing global- or user-flags, you are not allowed to manipulate all possible flags. See <ums.h> for protected flags. The following tags control what and how messages are selected, the 'input' and 'modes' of the select operation. SelStart, SelStop : LONG Limit the number of messages to be processed. The select operation will start with the message indicated by 'SelStart' and stop before the 'SelStop' message. In other words, start is included and stop is excluded. (0 < start <= messages to be processed < stop) This was different and partly buggy in MBP versions prior to V10.16. If no 'SelStart' is specified, the operation starts with the first message; if no 'SelStop' is specified, the operation stops at the last existing message. The following seven operations are mutually exclusive: 1) select by status SelReadGlobal : (none) SelReadLocal : (none) SelReadUser : STRPTR like SelWriteGlobal, SelWriteLocal, SelWriteUser, but specifys which flags to look at. Again, your user-flags are the default. SelMask, SelMatch : LONGBITS specify a mask and a match. If (status & mask) == match [status * mask = match], the message will be selected. SelParent : (node) with this tag specified, each message's 'parent' (reference; -> reply-chaining) will be inspected instead of its own status. 2) select by date SelDate : LONG the messages' dates are compared with the supplied date (in seconds since 1.1.1978) and only the younger ones will be selected. 4) select a tree SelTree : LONG you must specify the number of a message here. Then all messages being in the same reply-tree will be selected. 5) select a sub-tree SelSubTree : LONG like SelTree, but only the subtree (the one with the specified message as its root) is selected. 6) select a single message SelMsg : LONG select only the specified message. 7) select by text WMsgText, .. WMsgText + 127 : STRPTR when you specify one of these tags, the function selects all messages which have the supplied string in the specified field. The strings are compared case-INsensitive. SelQuick : (none) when this tag is specified, 'quick-search' is enabled for selecting texts. This means that only some CRCs on the texts are compared. This makes it possible to select also some wrong messages. Yet, due to the usage of 32-bit CRCs, the probability of selecting wrong messages is VERY low, you most likely will never experience this case. As 'quick-search' does not usually need to access mass- storage, it is VERY FAST. RESULT count - how many messages have been selected. Zero, when no message has been selected or an error has occured. EXAMPLE See SelectMail.c for examples on how to use this function. NOTES Although LONGBITS are used in the definition, the current implementation only uses/supports the lower 16 bits. SEE ALSO UMSSearch(), <usm.h>, </demo/SelectMail.c> ums.library/WriteUMSConfig ums.library/WriteUMSConfig NAME WriteUMSConfig -- Write an element to the global configuration. SYNOPSIS success = WriteUMSConfig( login, tags ) D0 D2 D3 BOOL WriteUMSConfig( LONG, struct TagIten * ); success = WriteUMSConfigTags( login, tag1, ... ) BOOL WriteUMSConfigTags( LONG, ULONG, ... ); FUNCTION Write or change something in the global UMS configuration. INPUTS Allowed tags: CfgData : STRPTR this tag holds the data to be written to a string. CfgUser : STRPTR name of the user whose config should be changed. CfgGlobalOnly : (none) change only global config elements. The following tags are mutually exclusive. Use exactly one of them. CfgName : STRPTR Name of the string that should be changed. If it does not already exist, the string will be created. If no tag CfgData is specified, then the string will be deleted. CfgDump : STRPTR write the current settings to a file with given name. RESULT success - whether it was possible and allowed to make the desired write or change. BUGS This function should provide tags to create or delete users, netgroups, akas, etc. These are not implemented yet. Tell the author (Martin Horneffer) when you need them! SEE ALSO ReadUMSConfig() ums.library/WriteUMSMsg ums.library/WriteUMSMsg NAME WriteUMSMsg -- Write a universal message to the UMS-MB. SYNOPSIS msgNum = WriteUMSMsg( login, tags ) D0 D3 D3 LONG WriteUMSMsg( LONG, struct TagItem * ); msgNum = WriteUMSMsgTags( login, tag1, ... ) LONG WriteUMSMsgTags( LONG, ULONG, ... ); FUNCTION Writes a message to the UMS message-base. This may be either a new message to create or an already existing message to be changed. The MBP checks correctness of the message and the users write-access concerning this message before writing it. It also performs dupe-checking, tries to link to a tree of reply-chains, creates all desired indices and computes the other users' read-access to this message. All the components of the message as well as information on how to do it are supplied as AmigaDOS compatible TagItems. INPUTS The following tags are allowed: WMsgText, .. WMsgText + 127 : STRPTR specify a certain text-field. A text fields is always one null-terminated string. Read the separate documantation to see what fields and what formats of these fields are allowed. A certain text-field (identified by its tag) may only appear once in a message. If a field is specified more than once in the tag list, only the latest will be used. WTextFields : UMSMsgTextFields specify more than one text-field. This points to an array of 128 string-pointers. All fields you don't want to specify must be NULL in this array. WMsgNum : LONG when you want to change an old message, you must use this tag to specify the number of the message to change. Don't use this tag when you just want to create a new message. WMsgDate : LONG this has a very special meaning. Specifying an AmigaDOS compatible date (seconds since 1.1.1978) with this tag indicates that you want to restore an old message from a backup rather than writing a new one. All users will have the 'old' flag set and not get this message as a new one when this tag is used. WChainUp : LONG in some cases it might be unsure or impossible for the MBP to build the correct reply-chain for a message. Use this tag to specify the number of the old message that is referred to by the new one. WHardLink, WSoftLink : LONG Writing a message with a Message-ID that already exists in the MB usually will lead to the detection of a 'dupe'. Yet in some cases it is necessary for UMS to allow multiple messages with the same Message-ID. This is made possible by the concept of message-'links'. With this concept, multiple messages sharing the same Message-ID (and perhaps some more fields) are organized in a circular linked list. To create such a linked list, you just write its first message as usual and remember its number. Then you write the other messages using one of the above tags to specify the number of the original message (or any of the already linked messages). The MBP may optimize storage space for message links by only storing the fields that differ between the fields and the original message. Nevertheless you always have to specify the whole message to write a link and you will always get the complete message when reading a link. All links to a message must consist of the same fields as the original message, but the contents of the fields may differ. There are two sorts of message-links, hardlinks and softlinks. Softlinks describe messages that have some fields in common (at least the Message-ID), but are really treated as individual messages. E.g. different parts of a splitted large message. Hardlinks, on the other hand, are treated as one message wherever possible. I.e. if you read one hardlinked message, all the other links will be marked as old, too. RFC crosspostings, for instance, should be made hardlinks. WAutoBounce : LONG If the msg to be written is addressed to a local user that doesn't exist or to an address that no exporter can export, there are two possible behaviours possible for the MBP: a) reject the message using error-no "NoReader", expecting the client to care about the undeliverable message b) keep the message, forwarding it to the local sysop or some kind of 'bounce-daemon', so that the writing client needs not to care about the message any more. This tag allowes to specify the desired behaviour, data=0 forces a), data=1 forces b). If this tag is not specified, the MBP will choose the behaviour as it wishes, maybe depending on whether the writing user is an exporter or not. WHide : LONG In some cases it might be desirable to write a message that can only by read by exporters and not by simple users, or the other way round. For instance control-messages that are of no interest to users by must be distributed over the net. Setting data to 0 is the same as the default. data=1 means that only exporters may view and read the message, data=2 makes the message invisible to exporters and only accessible to simple users. WHdrFill, WTxtFill : LONG specify how many bytes to reserve for later changes in the header/text of the message. The MBP may not be able to change an existing message if the change would increase the overall size (maybe after compression) of the message. Since such changes are neccessary in some special cases, the MBP can be told to reserve some space when writing a message the first time. Reserving more than actually needed is not a good idea, since it decreases performance and wastes space. The writer of a message usually should know whether or not he will change the message later on and to what extend he will increase the size of the message. WNoUpdate : LONG when writing a message, the 'Old'-flag in your user-status for the new message will usually be set. If you don't want this, use this tag and set its data to 1. RESULT msgNum - Number of the written message or NULL on failure. NOTES Changing an old message: You must _always_ give a complete message to WriteUMSMsg(), even when changing an old one! The MBP needs this to detect all changes made to the old message, including changed, added or deleted fields. Thus you need to read a message prior to changing it. Use RTextFields and WTextField for ReadUMSMsg() and WriteUMSMsg() when changing an old message! Otherwise you will loose fields unknown to you allication that might be still important to other applications! You may not be allowed to change certain fields of an existing message. Most likely those fields that are used by the MBP to compute all the users access-rights will be prohibited to change. SEE ALSO utility/tagitem.h